  <h1>SQL NAME TRANSFORMATIONS</h1>

  <p>The ODB compiler provides a number of mechanisms for transforming
     automatically-derived SQL names, such as tables, columns, etc.,
     to match a specific naming convention. At the higher level, we can
     add a prefix to global names (tables and, for some databases,
     indexes and/or foreign keys) with the <code><b>--table-prefix</b></code>
     option. Similarly, we can specify custom suffixes for
     automatically-derived
     index (<code><b>--index-suffix</b></code>; default is <code><b>_i</b></code>),
     foreign key (<code><b>--fkey-suffix</b></code>; default is <code><b>_fk</b></code>), and
     sequence (<code><b>--sequence-suffix</b></code>; default is <code><b>_seq</b></code>)
     names. Finally, we can also convert all the names to upper or lower
     case with the <code><b>--sql-name-case</b></code> option (valid values
     are <code><b>upper</b></code> and <code><b>lower</b></code>).</p>

  <p>At the lower level we can specify a set of regular expressions to
     implement arbitrary transformations of the automatically-derived SQL
     names. If we want a particular regular expression only to apply to
     a specific name, for example, table or column, then we use one of the
     <code><b>--</b><i>kind</i><b>-regex</b></code> options, where
     <code><i>kind</i></code> can be <code><b>table</b></code>,
     <code><b>column</b></code>, <code><b>index</b></code>,
     <code><b>fkey</b></code>, <code><b>sequence</b></code>, or
     <code><b>statement</b></code>. On the other hand, if we want our
     regular expressions to apply to all SQL names, then we use the
     <code><b>--sql-name-regex</b></code> option.</p>

  <p>The interaction between the higher and lower level transformations
     is as follows. Prefixes and suffixes are added first. Then the
     regular expression transformations are applied. Finally, if requested,
     the name is converted to upper or lower case. Note also that all of
     these transformations except for <code><b>--table-prefix</b></code>
     only apply to automatically-derived names. In other words, if a table,
     column, etc., name was explicitly specified with a pragma, then it
     is used as is, without applying any (except for the table prefix)
     transformations.</p>

  <p>The value for the <code><b>--*-regex</b></code> options is a Perl-like
     regular expression in the form
     <code><b>/</b><i>pattern</i><b>/</b><i>replacement</i><b>/</b></code>.
     Any character can be used as a delimiter instead of <code><b>/</b></code>
     and the delimiter can be escaped inside <code><i>pattern</i></code> and
     <code><i>replacement</i></code> with a backslash (<code><b>\</b></code>).
     You can also specify multiple regular expressions by repeating these
     options.</p>

  <p>All the regular expressions are tried in the order specified with the
     name-specific expressions (for example, <code><b>--table-regex</b></code>)
     tried first followed by the generic expressions
     (<code><b>--sql-name-regex</b></code>). The first expression that
     matches is used.</p>

  <p>As an example, consider a regular expression that transforms a class
     name in the form <code><b>CFoo</b></code> to a table name in the
     form <code><b>FOO</b></code>:</p>

  <p><code><b>--table-regex '/C(.+)/\U$1/'</b></code></p>

  <p>As a more interesting example, consider the transformation of class
     names that follow the upper camel case convention (for example,
     <code><b>FooBar</b></code>) to table names that follow the
     underscore-separated, all upper case convention (for example,
     <code><b>FOO_BAR</b></code>). For this case we have to use
     separate expressions to handle one-word, two-word, etc.,
     names:</p>

   <p><code><b>--table-regex '/([A-z][a-z]+)/\U$1/'</b></code></p>
   <p><code><b>--table-regex '/([A-z][a-z]+)([A-z][a-z]+)/\U$1_$2/'</b></code></p>

  <p>See also the REGEX AND SHELL QUOTING section below.</p>

  <h1>REGEX AND SHELL QUOTING</h1>

  <p>When entering a regular expression argument in the shell
     command line it is often necessary to use quoting (enclosing
     the argument in <code><b>"&nbsp;"</b></code> or
     <code><b>'&nbsp;'</b></code>) in order to prevent the shell
     from interpreting certain characters, for example, spaces as
     argument separators and <code><b>$</b></code> as variable
     expansions.</p>

  <p>Unfortunately it is hard to achieve this in a manner that is
     portable across POSIX shells, such as those found on
     GNU/Linux and UNIX, and Windows shell. For example, if you
     use <code><b>"&nbsp;"</b></code> for quoting you will get a
     wrong result with POSIX shells if your expression contains
     <code><b>$</b></code>. The standard way of dealing with this
     on POSIX systems is to use <code><b>'&nbsp;'</b></code> instead.
     Unfortunately, Windows shell does not remove <code><b>'&nbsp;'</b></code>
     from arguments when they are passed to applications. As a result you
     may have to use <code><b>'&nbsp;'</b></code> for POSIX and
     <code><b>"&nbsp;"</b></code> for Windows (<code><b>$</b></code> is
     not treated as a special character on Windows).</p>

  <p>Alternatively, you can save regular expression options into
     a file, one option per line, and use this file with the
     <code><b>--options-file</b></code> option. With this approach
     you don't need to worry about shell quoting.</p>

  <h1>DIAGNOSTICS</h1>

  <p>If the input file is not valid C++, <code><b>odb</b></code>
     will issue diagnostic messages to STDERR and exit with non-zero exit
     code.</p>

  <h1>BUGS</h1>

  <p>Send bug reports to the
     <a href="mailto:odb-users@codesynthesis.com">odb-users@codesynthesis.com</a> mailing list.</p>

  </div>
  <div id="footer">
    Copyright &#169; $copyright$.

    <div id="terms">
      Permission is granted to copy, distribute and/or modify this
      document under the terms of the
      <a href="http://codesynthesis.com/licenses/fdl-1.3.txt">GNU Free
      Documentation License, version 1.3</a>; with no Invariant Sections,
      no Front-Cover Texts and no Back-Cover Texts.
    </div>
  </div>
</div>
</body>
</html>
